Defining Hub Policies

Defining a policy on the hub allows you fine control over certain activities in the system. At present, policy allows you to control:

• tag/untag/move operations

• allowing builds from srpm

• allowing builds from SCM, and managing properties/behaviors related to the SCM if it is allowed

• allowing builds from expired repos

• managing the package list for a tag

• managing which channel a task goes to

• altering task priority

In the future, we expect to add more policy hooks for controlling more aspects of the system.

Policy configuration is optional. If you don’t define one, then by default:

• tag/untag/move operations are governed by tag locks/permissions

• builds from srpm are only allowed for admins

• builds from any SCM are only allowed for admins. It’s used when allowed_scms_use_policy is true in /etc/kojid.conf of the builders (false by default). And the SCM’s properies: use_common and source_cmd are set to their default values: False and ['make', 'source']

• builds from expired repos are only allowed for admins

• only admins and users with tag permission may modify package lists

• tasks go to the default channel

• vm tasks need admin or win-admin permission

• content generator import can be done by anyone

• all content ends in DEFAULT volume.

Configuration

The hub policy is configured in the hub.conf file, which is an ini-style configuration file. Policies are defined in the section named [policy]. Each name = value pair defines the policy of that name. With multiple line policies, successive lines should be indented so that the parser treats them as part of the whole.

Consider the following simple (and strict) example:

[policy]
tag =
    has_perm admin :: allow
    tag *-candidate :: allow
    all :: deny

This policy section defines a single policy (named ‘tag’). The policy is a series of rules, one per line. The rule lines must be indented. Each rule is a test and an action, separated by a double colon. The valid actions for current policies are ‘allow’ and ‘deny’. There are many tests available, though not all of them are applicable for all policies. Each test is specified by giving the name of the test followed by any arguments the test accepts.

Each rule in the policy is checked until a match is found. Upon finding a match, the action is applied. Our example above limits non-admins to tags ending in -candidate.

Getting a bit more complicated

The example above is very simple. The policy syntax also supports compound tests, negated tests, and nested tests. Consider the following example:

[policy]
tag =
    buildtag *epel* :: {
        tag *epel* !! deny
    }
    tag *-updates :: {
        operation move :: {
            fromtag *-updates-candidate :: allow
            fromtag *-updates-testing :: allow
            all :: deny Tagging from some tags to *-updates is forbidden.
        }
        operation tag && hastag *-updates-candidate *-updates-testing :: deny
    }
    all :: allow

This policy sets up some rules concerning tags ending in -updates and tags containing epel, but is otherwise permissive.

The first nested rule limits builds built from a tag matching epel to only such tags. Note the use of !! instead of :: negates the test.

For tags matching *-updates, a particular work-flow is enforced. Moving is only allowed if the move is coming from a tag matching *-updates-candidate or *-updates-testing. Conversely, a basic tag operation (not a move) is denied if the build also has such a tag (the policy requires a move instead).

For denied operations some clarifying message is sent to user. If there is no specific message (everything after action keyword), only generic ‘policy violation (policy_name)’ is sent, so it could be helpful to specify such messages in more complicated cases.

General format

The general form of a basic policy line is one of the following

test [params] [&& test [params] ...] :: action-if-true
test [params] [&& test [params] ...] !! action-if-false

And for nested rules:

test [params] [&& ...] [::|!!] {
    test [params] [&& ...] [::|!!] action
    test [params] [&& ...] [::|!!] {
        ...
        }
}

Note that each closing brace must be on a line by itself. Using !! instead of :: negates the entire test. Tests can only be joined with &&, the syntax does not support ||.

Available policies

The system currently looks for the following policies

• tag: checked during tag/untag/move operations

• build_from_srpm: checked when a build from srpm (not an SCM reference) is requested.

• build_from_scm: checked when a build task from SCM is executing on builder

• build_from_repo_id: checked when a build from a specified repo id is requested

• package_list: checked when the package list for a tag is modified

• channel: consulted when a task is created

• cg_import: consulted during content generator imports

• volume: determine which volume a build should live on

These policies are set by assigning a rule set to the given name in the policy section.

Note that the use of tag policies does not bypass tag locks or permissions

Note that an admin can bypass the tag policy by using --force.

Actions

Most of the policies are simply allow/deny policies. They have two possible actions: allow or deny.

The channel policy is used to determine the channel for a task. It supports the following actions:

use <channel>

• use the given channel

req

• use the requested channel

• generally this means the default, though some calls allow the client to request a channel

parent

• use the parent’s channel

• only valid for child tasks

• recommend using the is_child_task test to be sure

The priority policy is used to alter task’s priority. In most cases you should manage priorities by different channels and builders assigned to them. There is nevertheless few corner-cases which can benefit from altering task’s priority.

Note, that you can easily get to deadlock situation if this is not handled with caution (lower priority tasks will get assigned only if there is no higher priority task for given channel).

Note

For example OSBS use this mechanism to propagate higher priority tasks to its plugin. Deadlock problem is here mitigated by limiting policy to buildContainer tasks only. These tasks are consumed only by dedicated builders/channel, so they will not take priority over other types of tasks (e.g. newRepo or tagBuild tasks which could be blocked otherwise.

Technically it is very similar to channel policy. Only actions are different:

stay

• don’t touch the default priority of the task

set <int>

• set priority to this value

adjust +<int>

• increment default priority

adjust -<int>

• decrement default priority

The build_from_scm policy is used to assert if the SCM is allowed or not, like the basic allow/deny one. It is also used to manage the SCM’s properties as the same as the allowed_scms option of the koji builder. The actions could be defined as:

allow [use_common] [<source_cmd>]

• allow the SCM

• use(clone) the /common repo when use_common follows allow

• <source_cmd> is a optional shell command for preparing the source between checkout and srpm build. If it is omitted, it will follow the default value: make source. The explicit value: none means No source_cmd is defined.

deny [<reason>]

• disallow the SCM

• <reason> is the error message which is shown as the task result

Available tests

true

• always true. no arguments

all

• an alias of true

false

• always false. no arguments

none

• an alias of false

operation

• for tag operations, the operation is one of: tag, untag, move. This test checks its arguments against the name of the operation and returns true if there is a match. Accepts glob patterns.

• only applicable to the tag policy

package

• Matches its arguments against the package name. Accepts glob patterns.

version

• Matches its arguments against the build version. Accepts glob patterns.

release

• Matches its arguments against the build release. Accepts glob patterns.

tag

• matches its arguments against the tag name. Accepts glob patterns.

• for move operations, the tag name tested is the destination tag (see fromtag)

• for untag operations, the tag name is null and this test will always be false (see fromtag)

• for the build_from_* policies, tests the destination tag for the build (which will be null is –skip-tag is used)

fromtag

• matches against the tag name that a build is leaving. Accepts glob patterns

• for tag operations, the tag name is null and this test will always be false

• for move operations, the tag name test is the one that the build is moving from

• for untag operations, tests the tag the build is being removed from

• only applicable to the tag policy

target

• matches against the build’s target name. Accepts glob patterns.

hastag

• checks the current tags for the build in question against the arguments.

buildtag

• checks the build tag name against the arguments

• for the build_from_* policies the build tag is determined by the build target requested

• for the tag policies, determines the build tag from the build data, which will by null for imported builds

buildtype

• checks the build type(s) against the arguments

skip_tag

• checks to see if the –skip-tag option was used

• only applicable to the build_from_* policies

imported

• checks to see if the build in question was imported

• takes no arguments

• true if any of the component rpms in the build lacks buildroot data

• only applicable to the tag policy

is_build_owner

• Check if requesting user owns the build (not the same as package ownership)

• take no arguments

user_in_group

• matches the users groups against the arguments

• true if user is in /any/ matching group

has_perm

• matches the user’s permissions against the arguments

• true is user has /any/ matching permission

source

• test the build source against the arguments

• for the build_from_* policies, this is the source specified for the build

• for the tag policy, this comes from the task corresponding to the build (and will be null for imported builds)

policy

• takes a single argument, which is the name of another policy to check

• checks the named policy. true if the resulting action is one of: yes, true, allow

• additional policies are defined in the [policy] section, just like the others

is_new_package

• true if the package being added is new to the system

• intended for use with the package_list policy

is_child_task

• true if the task is a child task

• for use with the channel policy

method

• matches the task method name against glob pattern(s)

• true if the method name matches any of the patterns

• for use with the channel policy

user

• checks the username against glob patterns

• true if any pattern matches

• the user matched is the user performing the action

match

• matches a field in the data against glob patterns

• true if any pattern matches